Cream of the Crop 3/Cream of the Crop 3.iso/utility/reputil6.zip/READ.ME

Text File | 1993-12-19 | 26KB | 611 lines

.                             REPUTIL6--19DEC93




                        REP PACKET UTILITY PACKAGE  V6


                      Copyright (c) 1993, Frank F. Yates


                         Licensed for Free Public Use



.
.COPYRIGHT and LICENSE

          This package is copyright in 1993 by Frank F. Yates, but
          it is dedicated to public use without charge. It is free
          to all. The original distribution file "REPUTIL6.ZIP" may
          be distributed freely, provided that it is not changed
          in any respect. Any person may use the programs in this
          file for his own purposes without limitation. No part
          of this package be distributed except in the complete
          and original REPUTIL6.ZIP file.


.WARRANTY

   This package and the programs which it contains are absolutely not
   warranted in any way or for any purpose. So far as I know, it works
   just fine, but the risk of using it must be yours! Always be sure
   your files are backed up before trying ANY new software.


.FILE LIST

   This package contains the following files:

   1. FILE_ID.DIZ    Short Description for the BBS File Directory.
                     This is picked up by a BBS if you upload REPUTIL6.ZIP
                     and becomes their File Directory entry.

   2. READ.ME        Description of the package. Read this carefully.

   3. WRITEREP.EXE   Program to convert the text REPLY file into bbs.MSG.
                     Copy this to a utility directory of your choice.

   4. READREP.EXE    Program to convert bbs.MSG into formatted text messages.
                     Copy this to a utility directory of your choice.

   5. REPLY          Sample Reply file as input to WRITEREP.
                     Try executing WRITEREP on this to verify that it
                     produces an output file identical to MYBBS.MSG

   6. MYBBS.MSG      Result of executing WRITEREP on REPLY. This is the
                     file which goes into a REP packet for uploading.
                     You must compress this file and name it "bbs.REP"
                     before uploading as a message block. For example,
                     if your BBS was named MYBBS, you would want
                     a compressed file called MYBBS.REP, which you
                     would create by: PKZIP MYBBS.REP MYBBS.MSG

   7. ECHO           Text extracted back out of MYBBS.MSG by READREP


.FILE_ID.DIZ

               REPLY UTILITIES, Version 6 ...... 19 DEC 93
               Utility programs to read and write the
               ".REP" packets which are used to send a
               block of messages to a Bulletin Board (BBS).
               With these programs and a simple text editor
               you can create your own REP packets and
               upload batches of messages. These are simple
               programs with a lot of flexibility. FREEWARE


      The above is an exact copy of the FILE_ID.DIZ file included in
      in this REPUTIL V6 package (REPUTIL6.ZIP). The file name is noted
      by the BBS upon upload, and the brief description which the file
      contains is automatically entered into their File Directory. This
      system makes it unnecessary to enter on-line a lengthy description
      of the package to be uploaded. It also standardizes the description
      so that the author's original words are preserved as the package is
      passed by users from BBS to BBS by downloading and uploading.


.VERSION HISTORY

Version 3   (27 Sept 91)
------------------------
    * The first public release of REPUTIL


Version 4   (30 Sept 91)
------------------------
    * The Documentation was revised

    READREP.EXE Progrm
    ------------------
    * allow message lines of any length

    WRITEREP.EXE Program
    --------------------
    * Translate all null lines into a single space
    * Permit the use of "=" as alternative to ":" in Keyword syntax
    * Permit a leading "#" on the number of a referenced message
    * Improve the display of message headers during execution

Version 5   (17 Nov 93)
-----------------------
   * The Documentation was revised

   READREP.EXE Program
   -------------------
   * The output message header has been re-designed to be more similar
     to current PCBoard messages, and to accommodate the maximum
     field lengths (Subj:, From:, and To:) permitted by the QWK format
     ie. 25 bytes each.

   WRITEREP.EXE Program
   --------------------
   * The binary field at +123 bytes defining the Conference number
     was lengthened from 1 byte (255 limit) to 2 bytes (32,767 limit).
     Apparently this field has always been 2 bytes long. I just did not
     know it.

   * The default max line length is increased to 150 bytes. WRITEREP
     truncates lines greater than a limit controlled by the "LLX"
     parameter. This can be controlled by you, but previously the
     default was 80 bytes, which too-often truncates lines when you
     do not expect it to.

   * A "0" is now written into the "Ref" field of the QWK header record
     if no message is referenced. This change is required by PCBoard
     Version 15.0.

Version 6   (19 Dec 93)
-----------------------
   * The format produced by READREP was changed to make it even more like
     the long form of PCBoard messages, so that READREP output can be
     conveniently mixed with real PCBoard messages in your message database.

   * The MYBBS.REP file was deleted from the package because of problems
     with Upload Verification software in use at many BBS's. This software,
     which processes all uploaded files (except messages) to screen for
     duplication and for virus, unpacks and re-packs any embedded compressed
     files (such as MYBBS.REP). In the process, it renames them to .ZIP,
     thus creating confusion. The simplest solution seemed to be just
     eliminating the MYBBS.REP file from the package.

.The "." marks on the document sections

   These little dots (just ordinary periods) are "Module Identifiers", which
   permit "FRANK's READER" to create an index of a document or a message
   file and to access the sections individually from the index. Frank's
   Reader is ideal for studying text files (such as this one) without having
   to print them, but it is not required in order to use REPUTIL.

   Frank's Reader is very handy for reading the messages in any format and
   for the general management of text files. It is fully functional
   shareware. Version 18, (FR18.ZIP) should be available anywhere you find
   REPUTIL6.ZIP.

.
.INTRODUCTION

   Bulletin Board Systems (BBS) in the beginning were designed for
   on-line interactive use, where the user would read messages while
   connected to the board, and compose replies and new messages in real
   time. This can still be done, but is no longer the common practice.
   The thousands of messages which are available on most BBS make live
   interaction too time consuming and too costly (in phone bills). Also,
   the quality of work which can be done in real-time is often not the
   best. The common practice today is for users of BBS systems is to
   work off-line, where they:

   1. Call the BBS and download a packet of messages, either thru a
      Mail Door, or directly from the board. Then immediately hang up.

   2. Read these messages at leisure, using an Off-Line Mail Reader,
      (such as "SLMR", the Silly Little Mail Reader, which is free now).
      Good replies and new messages are composed using such a reader
      or other software, creating a "REP" packet containing them.

   3. Call the BBS again, and upload the REP packet, from which the BBS
      extracts the replies and new messages and enters them into its
      message database.


.QWK/REP FORMAT

   The format of the QWK/REP packets is used by many Bulletin Board
   Systems and has become essentially an industry standard. It is best
   described in a file: QWKLAY16.ZIP by Patrick Y. Lee, which is
   available for download on many BBS. An excerpt from that file,
   provides background on the QWK/REP system.

   ------------------- Excerpt from QWKLAY16.ZIP ----------------------
   [1.2]  History

   The QWK-format was invented by Mark "Sparky" Herring in 1987.  It was
   based on Clark Development Corporation's PCBoard version 12.0 message
   base format.  Off-line mail reading has become popular only in recent
   years.  Prior to summer of 1990, there were only two QWK-format off-
   line mail reader programs.  They were Qmail DeLuxe by Mark Herring and
   EZ-Reader by Eric Cockrell.  Similarly for the doors, there were only
   two -- Qmail by Mark Herring and MarkMail by Mark Turner.  They were
   both for PCBoard systems.

   A lot has changed in both off-line reader and mail door markets since
   summer 1990.  Now, there are more than a dozen off-line mail readers
   for the PC.  Readers for the Macintosh, Amiga, and Atari exist as
   well.  There are over a half dozen doors for PCBoard, and QWK-format
   doors exist for virtually all of the popular BBS softwares.  All of
   these happened in less than two years!  More readers and doors are in
   development as I write this, keep up the excellent work.  In addition
   to doors, some BBS softwares has QWK-format mail facility built in.

   Off-line mail reading is an integral part of BBS calling.  Conference
   traffic and selection on all networks have grown dramatically in re-
   cent years that on-line reading is a thing of the past.  Off-line mail
   reading offers an alternative to reading mail on-line -- It offers
   speed that cannot be achieved with on-line mail reading.

   The reason why QWK-format readers and doors seem to have gained popu-
   larity is probably dued to its openness.  The format is readily avail-
   able to any programmer who wishes to write a program that utilize it.
   Proprietary is a thing of the past, it does not work!  Openness is
   here to stay and QWK-format is a part of it.

   QWKLAY16.ZIP is Copyright 1992 by Patrick Y. Lee.

   The QWK-format is Copyright 1987 by Sparkware.

   ----------------- End-of-Excerpt from QWKLAY16.ZIP -----------------


.OFF-LINE MAIL READERS

   Many "Mail Readers" are available, some of which are very good. Most
   read ".QWK" packets and create ".REP" packets. The readers provide a
   convenient platform for viewing and generating messages. I use one
   myself, and it is not my purpose to denigrate Mail Readers. They do
   have certain limitations however, which are overcome by the REPUTIL
   utilities. I consider REPUTIL to be an adjunct to a mail reader
   rather than a replacement. REPUTIL itself cannot be called a Mail
   Reader because it does not include many of the automatic features
   common in Mail Readers.

   REPUTIL can be used without a Mail Reader though, and it can do some
   things which most Mail Readers can't, such as reply to messages which
   are not available locally in QWK packets. It can also read messages of
   any length, which some Mail Readers can't.


.REPUTIL  Its Purpose, Function, and Use

   The REPUTIL package contains two programs (WRITEREP, and READREP)
   which will run on IBM PC type computers under the DOS operating
   system and others which are DOS compatible. It also contains this
   file, which may have some merit by itself as information for BBS
   users.

   BBS messages must necessarily spring from a text editor. Often this
   editor is called from a mail reader, and may even be built into the
   mail reader. You can use any old text editor however to generate a
   message, or even a word processor in text mode, and you do not need a
   Mail Reader to do it. Once having produced one or more messages in a
   text file, it is easy using WRITEREP to create a REP packet which can
   carry these messages up to a BBS.

   The instructions on how to do this follow.


.
.HOW TO CREATE A REPLY FILE

   The first step in uploading a batch of messages is to write the
   messages by any means available, and accumulate them in a text file,
   which for convenience we will call "REPLY". As you write each
   message, include a "Header" line before the message text containing
   the routing information needed by the BBS. The syntax of the Header
   is:

# To:xxx   Sub:xxx

   The "#" must be in column 1, and identifies this line as a message
   header. The two keyword parameters which follow are required for all
   messages. To: is the addressee of the message, Sub: is the subject.
   Either of these can contain up to 25 characters, including embedded
   blanks. "Subj" will work instead of "Sub" if you prefer. If the
   subject entered is too long, it will be truncated by WRITEREP at 25
   characters.

   If you want to send a message to a Conference other than "0", then
   you may add Conf:n  or Cnf:n to the header, where "n" is the
   Conference number. The number must be used rather than the name
   because that is the requirement for the REP packet, and WRITEREP is
   not set up to process conference names. The Conference numbers are
   available from the Conference list generated by the (J)oin command
   (for PCBoard BBS). They also appear in the CONTROL.DAT file of a QWK
   packet, if you happen to have one of those.

   If your message replies to or references another message, you may
   cite the number of that message: Ref:n  This permits your message
   to be easily found by others as part of the thread.

   If you wish your message to be private rather than public, you may
   add the word "PVT" as the first word in the line after "#". An
   example of a message using all these options follows:

============================================================================
#PVT  To:Somebody  Sub:Syntax Example #1  Conf:50
Hello,
         This is a message illustrating the syntax of the control header for
batch messages to be processed by WRITEREP into an un-compressed .REP packet.
Other examples can be found in the sample REPLY file which comes with the
REPUTIL package.

Regards,
           Frank
============================================================================

   You may use small letters or capitals for the keyword parameters, and
   the value "xxx" may be separated from the ":" by a space if you
   prefer. The beginning of each keyword must be separated from the end
   of the preceding data field by one or more spaces. The parameters
   may be written in any order, except that if "PVT" is used, it must be
   first.


.HEADER LINE SYNTAX

   * A "#" in column 1 is required for all headers, and this character
     must not appear in column 1 of any line of text in your messages.
     This is the way WRITEREP identifies the end of the previous message
     and the beginning of a new one.

   * All control parameters must appear on a single line, which can be
     longer than 80 bytes if necessary.

   * The parameters can be in any order, except "PVT", which must be
     first if it is used.

   * The parameters are separated from each other by one or more spaces.
     Commas are not used.

   * Additional spaces may be used in the header line for readability.
     They will be ignored, except within the To, From, and Subject fields,
     where they are retained as entered.

   * Parameter names and values may be in small letters or capitals, or
     mixtures of these.

   * Four of the parameters (CNF, LCX, LLX, REF) require numeric values.
     Supplying a a non-numeric value for one of these will cause WRITEREP
     to abend.

   * In the keyword parameters, "=" may be used in place of ":" as a
     separator, whichever you prefer. This is true for either the command
     line parms or the message headers.

   * The value assigned to the parameter may begin immediately following
     the separator (: or =), or it may be separated by one or more blanks.


.COMMAND LINE SYNTAX

The command line syntax for WRITEREP is:

                                -------- Optional ----------
  C:> WRITEREP infile outfile  {Fr:your name} {LCX:n} {LLX:n}

   If you do not supply infile and/or outfile, the program will ask you
   for these names. The other parameters are optional, but including your
   name is recommended, because otherwise you will have to include it in
   the first message header, which you might forget to do.

   The infile name can be anything, but the outfile name is critical. It
   must be of the form "bbs.MSG", where "bbs" is the identifier used by
   your BBS for Mail Door Packets. If you don't know what this is, ask
   your SYSOP. It is necessary to scratch any existing output file
   before executing WRITEREP because otherwise an unusable file could
   result from a combination of new messages with the old ones.


The command line syntax for READREP is:

   C:> READREP infile outfile

   Again if the input and output files are not supplied as command line
   parameters the program will prompt you for them.


.PARAMETER LIST

   The following parameters may be used in message header lines. "To"
   and "Sub" are required for every message, as is "Fr" unless you have
   included that in the command line. The other parameters are optional.

   PARM                            DESCRIPTION
   --------    -----------------------------------------------------------
   PVT         Private Message Flag.  If used, must be the first parameter

   Cnf:n       Conference Number   (defaults to 0)
   Conf:n

   Fr:xxx      Your Name as sender of the message  (25 chars max)
   From:xxx

   LCX:n       Max number of lines per message. Messages will be split into
               parts if this number is exceeded  (default 95)

   LLX:n       Maximum length of a message line. (default 150)

   Ref:n       Number of Referenced Message  (optional)

   Sub:xxx     Subject of the message  (25 chars max)
   Subj:xxx

   To:xxx      Addressee of Message  (25 chars max)


   The following parameters may be used on the command line.
   ---------------------------------------------------------
   Fr:xxx  From:xxx  LCX:n  LLX:n


.HOW TO CREATE a REP PACKET and POST YOUR MESSAGES

   Once you have a REPLY file containing one or more messages, the
   following steps will send your message(s) to the BBS. A BAT procedure
   can automate them for you, as described in the next section.


1. Execute WRITEREP to create a file called "bbs.MSG".
   ---------------------------------------------------
   C:>WRITEREP reply bbs.MSG       (NOTE: replace "bbs" with your BBS name)


2. Compress bbs.MSG into bbs.REP
   -----------------------------
   C:>PKZIP bbs.REP bbs.MSG        (NOTE: the operand order is reversed)

   "bbs" is a word, not more than 8 bytes long, which is used to
   define your BBS in QWK and REP packets. You can ask your SYSOP, or
   download a QWK packet and see what it is called.

   NOTE: It is important to enter CAPITAL LETTERS on this command,
   because if you enter small letters the REP file may have small
   letters in its name (under some operating systems), and then you
   may find that the BBS will reject the file for upload. The BBS
   wants CAPITAL letters in its REP packet names.

   For example, the RESEARCHER's BBS creates QWK packets called
   "RESEARCH.QWK". To upload replies to this BBS, you send up a file
   called "RESEARCH.REP".


3. Call the BBS, and upload the bbs.REP packet
   -------------------------------------------
   This can be direct to a PCBoard V15.0 BBS via a "QWK U" command,
   or thru a variety of Mail Doors on various types of BBS.


.AUTOMATIC EXECUTION

   It is convenient to automate the conversion of the REPLY file into
   a REP packet. Following is a procedure which does this. It requires that
   you first identify the BBS in your DOS environment table. Do this by the
   command:> SET BBS=bbs   (for "bbs", enter the correct identifier).
   You could of course replace %BBS% in this procedure by %1, and supply
   the BBS name as an operand, if that would be more convenient.
   NOTE: Use CAPITAL LETTERS in your "SET BBS=" command. See note in the
   the previous section.


   @ECHO OFF
   REM REPGEN.BAT--10NOV93  Translate the REPLY file into a REP packet
   REM
   REM ---Convert messages in REPLY to a REP Packet for PCBoard
   IF "%BBS%"=="" GOTO NOBBS
   IF EXIST %BBS%.MSG DEL %BBS%.MSG
   WRITEREP REPLY  %BBS%.MSG  Fr:Frank Yates    ****INSERT YOUR NAME HERE****
   REM
   REM ---Zip it up for transmission
   IF ERRORLEVEL 1 GOTO FIN
   IF EXIST %BBS%.REP DEL %BBS%.REP
   PKZIP -a %BBS%.REP %BBS%.MSG
   REM
   REM ---Convert back to ASCII to check   **** This step is optional ****
   IF ERRORLEVEL 1 GOTO FIN
   READREP %BBS%.MSG ECHO
   IF ERRORLEVEL 1 GOTO FIN
   IF EXIST ECHO FR ECHO        <<< This calls Frank's Reader to look at ECHO
   GOTO FIN
   :NOBBS
   ECHO *** SET BBS
   :FIN


NOTES:

1. Your name can be supplied as a command line parameter to WRITEREP, as
   illustrated in the above procedure, or it can be supplied in the first
   message header. Putting it in the procedure is easier, and is recommended.
   If you do both, the name used in any message header becomes the new
   default for subsequent messages in the packet.

   The name you supply must match exactly the name which you use to sign on
   to the BBS. This name is inserted into the REP packet, and your messages
   will be refused if the name is not right. The syntax is "Fr:first last".
   Either small letters or capitals will work.

2. You may specify two additional parameters on the WRITEREP execution line
   if you wish:

   LCX=n   The maximum number of lines in a message out of WRITEREP.
           The default is 95. Messages containing more than 100 lines
           occur frequently (unfortunately), and messages containing
           many hundreds of lines are seen now and then. It is good
           practice however to limit any single message to not more
           than 95 lines to be sure that everyone who sees your message
           will see it all.

           With WRITEREP, you can create a message as long as you like,
           and WRITEREP will split it into smaller messages not exceeding
           the value of LCX.

   LLX=n   The maximum length of any line in a message. The default is 140.
           Input lines longer than this will be truncated. Ordinarily new
           message lines should be limited to 71 columns so that they are
           not folded on some computers, and to leave room for quoting
           prefixes added by those who reply to and quote your messages.
           The purpose of LLX is to allow you to insure that message lines
           do not exceed some desired limit for a particular application.


.HOW TO INSPECT A REP PACKET

   You may want to double-check your first few REP packets to be sure
   that you have done it all right.

        C:>PKUNZIP bbs.REP          (recovers "bbs.MSG")

        C:>READREP bbs.MSG ECHO     (creates ECHO file, which is text)


.HOW TO INSPECT A QWK PACKET

   READREP was not intended to read QWK packets. This was a surprise
   extra benefit resulting from the similarity in format between REP
   and QWK. The messages in a QWK packet are contained in the file
   "MESSAGES.DAT", but they have almost the same format as the
   "bbs.MSG" file in a REP packet. The main difference is that the
   Conference number field in QWK packets is used to contain the message
   number. To figure out the conference number of a message, you need
   to access the xxxx.NDX files and search for a pointer to that message.
   READREP does not do this.

   Ordinarily there is no reason to use READREP for QWK packets, since
   if your intent is to process messages in text form, you are better
   off downloading compressed text messages in the first place instead of
   QWK packets. For one thing, that way your subject and address fields
   will not be truncated to 25 bytes.

   There is one case however in which READREP is handy with respect to
   QWK packets. If you are reading messages with your Mail Reader and
   come across in interesting one which has been truncated at 100 lines
   or 150 lines, etc. you can note the number of the message and later
   use READREP to extract it from the QWK packet. I used to do this
   a lot with Internet and UseNet messages before I stopped using QWK
   packets and mail readers altogether.

 STEP
   1.   C:>PKUNZIP bbs.QWK                (recovers "MESSAGES.DAT")

        This step may not be necessary if you can shell out of your
        Mail Reader and look at its work directory, or exit from it
        and leave the work directory intact.

   2.   C:>READREP MESSAGES.DAT NEW.MSG   (creates NEW.MSG file)


.NAMES and ADDRESSES

   CLARK DEVELOPMENT Co, Inc.   Source of the PCBoard BBS software
   6000 S. Fashion Blvd. Suite 101
   Murray, UT  84107  U.S.A.
   Voice:  [phone]
     Fax:  [phone]
     BBS:  [phone]

   PKWARE Inc.                  Source of the "PKZIP" Compression Utilities
   9025 North Deerwood Drive
   Brown Deer WI 53223
   BBS: [phone]

   RESEARCHER's BBS             Our local BBS. They have many many files.
   P.O Box 1715                 The SYSOPs are friendly.
   Lancaster, CA 93539          You can register as a guest to access all
   BBS: [phone]          messages and download certain sofware.

   Frank F. Yates               Who put REPUTIL together for your benefit.
   21340 N. Charlene Place      To reach me, leave a message on Researcher's,
   California City, CA 93505    or send to Internet: [e-mail]